MoneyPrinterTurbo 全览

一站式 AI 短视频生成工具：提供视频主题或关键词，自动生成脚本、匹配素材、合成字幕与配音，一键产出高清短视频。

一、项目概述

MoneyPrinterTurbo 是一个开源的 Python 项目（MIT License），由 harry0703 维护，GitHub 上约 115k Star / 17.5k Fork。核心定位是把「写文案 → 找素材 → 配音 → 字幕 → 合成 → 发布」这条短视频制作链路，交给一条可配置的 自动化任务流水线 完成，人只需要提供主题词。

二、功能特性

• 四种使用方式：AI Agent（读 Skill 文档自动装、配、生成）、WebUI（Streamlit 图形界面）、API（REST）、CLI（命令行）。
• 脚本生成：LLM 自动生成多语言脚本，也支持直接提供自定义脚本。
• 高清尺寸：竖屏 9:16（1080x1920）、横屏 16:9（1920x1080）、方形 1:1。
• 批量生成：一次生成多个视频，挑最满意的一个。
• 语音合成：Edge TTS、Azure Speech、SiliconFlow、Google Gemini、小米 MiMo、ElevenLabs、Chatterbox、Fish Audio，支持实时试听，也支持无配音/自定义音频。
• 字幕：可调字体、位置、颜色、大小、描边、背景样式。
• 背景音乐：随机 / 指定 / AI 生成，可调音量。
• 素材来源：本地素材、Pexels / Pixabay / Coverr 免费素材，以及 WaveSpeed AI 文生视频按脚本关键词直接生成画面。
• 跨平台发布：生成完成后通过 Upload-Post 自动上传 TikTok / Instagram / YouTube Shorts。
• 预设与安全：生成设置可导出/导入预设，支持备份/恢复所有 API Key。

三、架构分层与职责

代码按「控制器 → 服务 → 模型」三层职责划分，四个入口（WebUI / API / CLI / Agent）最终都汇聚到同一个任务流水线 app/services/task.py:start()。

入口层：  WebUI (Streamlit)   API (FastAPI /api/v1)   CLI (cli.py)   AI Agent (Skill)
                    └──────────────┬─────────────────────┘
服务层：  task.py（流水线调度）→ llm / voice / material / subtitle / video / bgm / upload_post
模型层：  schema.py（Pydantic 数据模型）、llm_provider.py（模型注册表）、const.py
运行层：  state.py（任务状态）、任务队列（内存 / Redis）、storage/（产物）、ffmpeg

四、行为分析（系统做什么）

1. 用例图（整体行为）

图 1 · 用例图：系统对外提供的行为

demo（CLI 入口对应「生成完整视频」）

uv run python cli.py --video-subject "人工智能如何改变日常生活"

2. 活动图（视频生成主流程）

图 2 · 活动图：一次任务的完整流程（含失败分支与可选发布）

demo（提前结束在中间产物）：利用 --stop-at 只生成脚本或配音，作为独立中间接口使用。

# 只生成脚本，不配音不合成
uv run python cli.py --video-subject "春天适合出发" --stop-at script

# 先生成脚本，再提供自定义脚本跳过 LLM，直接到配音
uv run python cli.py --video-script "你的完整文案" --voice-name no-voice --stop-at video

3. 时序图（一次完整任务）

图 3 · 时序图：从 API 提交到成片的跨服务协作

demo（HTTP API 提交任务）

curl -X POST http://127.0.0.1:8080/api/v1/videos \
  -H "Content-Type: application/json" \
  -d '{"video_subject":"深海里的微光","video_aspect":"9:16","video_source":"pexels","voice_name":"zh-CN-XiaoxiaoNeural-Female"}'

# 返回 {"task_id":"..."}，随后轮询查询状态：
curl http://127.0.0.1:8080/api/v1/tasks/<task_id>

4. 状态机图（任务与发布状态）

图 4 · 状态机图：任务状态与跨平台发布状态的流转

demo（状态常量，来自 app/models/const.py）

TASK_STATE_FAILED     = -1   # 失败
TASK_STATE_COMPLETE   = 1    # 完成
TASK_STATE_PROCESSING = 4    # 处理中

CROSS_POST_STATE_PENDING = "pending"     # 待发布
CROSS_POST_STATE_PROCESSING = "processing"
CROSS_POST_STATE_COMPLETE = "complete"
CROSS_POST_STATE_FAILED = "failed"

五、结构分析（系统由什么组成）

1. 部署图

图 5 · 部署图：Docker Compose 与本地手动部署两种形态

demo（Docker 一键部署）

cd MoneyPrinterTurbo
cp config.example.toml config.toml      # 首次需生成配置
docker compose -f docker-compose.release.yml up
# WebUI: http://127.0.0.1:8501
# API 文档: http://127.0.0.1:8080/docs

2. 组件图

图 6 · 组件图：入口层、服务层、模型层与外部服务

demo（组件依赖关系体现在 import 上）

# 四个入口最终都调用同一个流水线
from app.services import task as tm        # WebUI / API / CLI 都这样用
result = tm.start(task_id=task_id, params=params, stop_at="video")

3. 包图（源码目录）

图 7 · 包图：项目目录结构与调用关系

demo（目录速览）

MoneyPrinterTurbo/
├── app/               # 后端核心
│   ├── asgi.py        # FastAPI 应用
│   ├── router.py      # 路由汇总
│   ├── config/        # 配置加载 (config.toml)
│   ├── controllers/   # API 控制器 (v1/video.py, v1/llm.py, manager/)
│   ├── models/        # schema.py / llm_provider.py / const.py
│   ├── services/      # task/llm/voice/material/subtitle/video/bgm/state...
│   └── utils/         # 工具与路径安全
├── webui/Main.py      # Streamlit 界面
├── cli.py             # 命令行入口
├── main.py            # API 服务启动入口
├── resource/          # songs 背景音乐、fonts 字幕字体
├── storage/           # 运行时产物：tasks/ cache_videos/ bgm/ local_videos/
└── models/            # whisper 本地模型（可选）

4. 类图（核心模型与服务）

图 8 · 类图：核心数据模型（VideoParams / MaterialInfo）与流水线对服务的调用关系

demo（构造一个视频任务的参数）

from app.models.schema import VideoParams, MaterialInfo

params = VideoParams(
    video_subject="一杯手冲咖啡的细节",
    video_source="local",
    video_materials=[MaterialInfo(provider="local", url="./1.mp4", duration=0)],
    voice_name="zh-CN-XiaoxiaoNeural-Female",
    subtitle_enabled=True,
)

六、核心服务详解

task.py 任务流水线

整个系统的「发动机」。所有入口最终都会调用 task.start()，它按阶段推进并维护任务状态：

1. preflight：校验 ffmpeg 可用性、BGM 供应商 API Key、配乐提示词长度；失败则任务立即失败。
2. script：调用 LLM 生成脚本（或直接使用自定义脚本）。
3. terms：素材源为在线时，用 LLM 根据脚本提炼素材搜索词。
4. audio：TTS 合成配音（或静音 / 自定义音频文件）。
5. subtitle：用 edge 时间戳或 whisper 转写生成字幕。
6. materials：在线下载素材或预处理本地素材。
7. video：ffmpeg 拼接片段、加转场、烧录字幕、混入配音与 BGM，产出成片。
8. cross_post（可选）：完成后异步提交到 TikTok / Instagram / YouTube。

任务一旦失败，会在状态里记录 failed_stage 与错误信息，方便定位是哪个环节出的问题。

llm.py 大模型服务

统一封装各家 LLM 的 Chat Completions 接口，屏蔽响应差异。提供三个能力：

• generate_script()：按主题生成短视频脚本（可指定语言、段落数 1-10、附加要求、自定义系统提示词）。
• generate_terms()：从脚本提炼素材搜索关键词，可选按脚本叙事顺序排序（配合素材顺序拼接）。
• generate_social_metadata()：生成发布平台的标题 / 描述 / 标签元数据。

供应商列表维护在 app/models/llm_provider.py（默认模型、默认 Base URL 的注册表），在 config.toml 里改 llm_provider 即可切换，也可覆盖模型名与 Base URL。

voice.py 语音合成

封装多种 TTS 供应商，音色名带前缀区分：

另支持 voice_volume / voice_rate 调节，以及自定义音频文件直接作为旁白。

material.py 素材服务

• 在线搜索下载（默认）：Pexels / Pixabay / Coverr 按搜索词检索现成的免费图片/视频，并做宽高比（9:16 / 16:9 / 1:1）过滤与缓存（cache_manager.py）。
• AI 文生视频（可选）：WaveSpeed 按关键词用外部文生视频扩散模型（默认 Seedance）直接生成全新画面，按次计费。注意这是独立的视频生成模型服务，不是 LLM。
• 本地素材：预处理本地图片/视频，支持目录外文件复制到受控目录后再使用。
• TwelveLabs 集成（可选）：用 Marengo 模型对素材做语义重排，提升素材贴合度。

subtitle.py 字幕生成

• edge 模式：直接用 TTS 的单词时间戳生成字幕，速度快、无需 GPU（默认）。
• whisper 模式：本地 faster-whisper 转写音频得到更准的时间轴（需下载模型，默认 large-v3）。
• 字幕支持字体、颜色、大小、描边、位置（top/center/bottom/custom）、背景与圆角。

video.py 视频合成

基于 moviepy 调用 ffmpeg：把素材片段裁剪/变速到目标时长，按 concat_mode（random/sequential）拼接，应用转场（FadeIn/FadeOut/Slide/Zoom 等），烧录字幕，混入配音与 BGM，输出指定尺寸的高清视频。支持硬件编码（h264_nvenc / h264_videotoolbox 等）自动回退 libx264，支持批量出多版本成片。

注意：这里的"合成"是剪辑拼接（concat_video_clips_with_ffmpeg 把多个片段按时间顺序接起来，combine_videos 混入音频/字幕），不是逐帧生成的连续动画。画面内容完全来自素材源，本模块不创造任何像素。

bgm / AI 配乐服务

• bgm.py：管理内置 resource/songs 与上传的 BGM，支持 random / custom 选择与音量调节。
• sonilo.py：Sonilo 按视频内容生成匹配的原创配乐。
• elevenlabs_music.py：ElevenLabs 视频配乐（与 TTS 共用 Key）。

state.py 与任务队列

• state.py：任务状态中心，负责任务记录的写入、查询、分页与删除。
• 任务队列：默认内存队列（InMemoryTaskManager）；配置 enable_redis=true 后用 RedisTaskManager。并发数 max_concurrent_tasks（默认 5）、队列上限 max_queued_tasks（默认 100），满了返回 429。

upload_post.py 跨平台发布

通过 Upload-Post 第三方服务，把成片自动发布到 TikTok / Instagram / YouTube Shorts。发布是异步的（线程池），不阻塞视频结果返回；配置 upload_post_auto_upload=true 后自动触发。进程重启后不再恢复未完成的发布（Redis 中确认失去执行进程的状态会被收敛为失败，避免任务无法删除）。

七、实战演示操作手册

部署方式速览

# macOS / Linux 手动部署
git clone https://github.com/harry0703/MoneyPrinterTurbo.git
cd MoneyPrinterTurbo
uv python install 3.11
uv sync --frozen
sh webui.sh                      # WebUI → http://127.0.0.1:8501
uv run python main.py            # API   → http://127.0.0.1:8080/docs

首次配置

1. 首次启动自动根据 config.example.toml 生成 config.toml。
2. 在 WebUI「基础设置」中配置：大模型 Provider（如 moonshot 的 API Key）、素材源（Pexels 需注册 API Key，Edge TTS 免 Key）、需要的 TTS。
3. 若用 whisper 字幕：subtitle_provider = "whisper"，可把 whisper.model_size 设为 large-v3-turbo 以减小体积（约 1.6GB）。

WebUI 生成演示

1. 启动后浏览器打开 WebUI。
2. 「基础设置」填好 API Key 等配置（或导入预设）。
3. 「视频生成」页输入主题（如「城市醒来的时刻」），选尺寸 9:16 / 16:9、配音音色、字幕开关、BGM。
4. 点「开始生成」，等待任务跑到 100%。
5. 在任务管理里预览 / 下载成片，或一键发布到已配置平台。

CLI 生成演示

# 1) 最简单：主题 → 完整视频（默认 Edge TTS，无需 TTS Key；LLM 与 Pexels Key 在 config.toml）
uv run python cli.py --video-subject "人工智能如何改变日常生活"

# 2) 用本地素材生成
uv run python cli.py --video-subject "我的旅行" \
  --video-source local --video-materials "./1.mp4,./2.mp4"

# 3) 只生成脚本
uv run python cli.py --video-subject "春天适合出发" --stop-at script

# 4) 自定义脚本 + 无配音（仅字幕），直接到成片
uv run python cli.py --video-script "你的完整文案" --voice-name no-voice --stop-at video

# 查看全部参数
uv run python cli.py --help

API 生成演示

# 生成脚本
curl -X POST http://127.0.0.1:8080/api/v1/scripts \
  -H "Content-Type: application/json" \
  -d '{"video_subject":"深海里的微光","paragraph_number":1}'

# 提交成片任务
curl -X POST http://127.0.0.1:8080/api/v1/videos \
  -H "Content-Type: application/json" \
  -d '{"video_subject":"深海里的微光","video_aspect":"16:9","voice_name":"zh-CN-XiaoxiaoNeural-Female"}'

# 查询任务（返回状态、产物 URI、videos 列表）
curl http://127.0.0.1:8080/api/v1/tasks/<task_id>

# 流式播放 / 下载产物（默认挂载在 /stream 与 /download 下）
# 若配置了 app.api_key，需要携带 x-api-key 请求头

完整交互式文档在 http://127.0.0.1:8080/docs（Swagger UI）。

AI Agent 方式

使用这个 Skill：https://raw.githubusercontent.com/harry0703/MoneyPrinterTurbo/main/docs/skill/SKILL.md
帮我生成一个主题为“人工智能如何改变普通人的日常生活”的视频。

Agent 会自动完成克隆、配置依赖、填 Key（缺时才会问你）并返回生成的视频文件路径。

常见问题

八、参数指令速查手册

CLI 全参数表

config.toml 配置速查

API 端点速查表

流水线阶段与 stop-at

整理自 MoneyPrinterTurbo 官方 README 与源码（app/controllers、app/services/task.py、cli.py、config.example.toml）。仓库：github.com/harry0703/MoneyPrinterTurbo（MIT）。